feat: mergeStateStatus in delta summary + opt-in baseline-state emission - #20
Merged
Merged
Conversation
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b903d4ba5f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…lowed A CLEAN->BEHIND transition (base branch advances, nothing else changes) was dropped because mergeStateStatus was excluded from the fingerprint comparison, silently writing the new status to the snapshot and leaving consumers at a stale 'ready to merge'. Treat it as a compared field like mergeable: transitions fire an updated delta and enter the delta id. A snapshot predating the field is suppressed pairwise so the first post-upgrade tick does not emit a fleet-wide spurious burst.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two additive contract features requested by the downstream consumer
gh-delta-orca. Both are additive underreport.schemaVersion === 1(no bump), fail-closed, and independently shippable.Feature 1 —
mergeStateStatusin the delta summarysummary.mergeableonly distinguishesmergeable | conflicting | unknown, so a PR that is approved, CI-green andmergeablebut which GitHub still refuses to merge — because the branch is behind the base (repos that require branches be up to date) or blocked by an unsatisfied protection rule — was indistinguishable from a genuinely ready PR. Consumers emitted a false "ready to merge".summary.mergeStateStatus(PR deltas under--summaries), sourced from GitHub'smergeStateStatusin the same single observation that builds the fingerprint (no extra fetch).behind | blocked | clean | dirty | draft | has_hooks | unstable | unknown. Null/absent/unrecognized →unknown("not computed", exactly likemergeable: unknown).ciChecks/reviewSummary), so it never fires a spurious delta and older snapshots that gain the key diff to zero.DELTA_SUMMARY_FIELDS/DELTA_SUMMARY_ENUMS,--help-jsonoutput.deltaSummaryFields/output.deltaSummaryEnums), the contract summary + fingerprint tables, and the README.Feature 2 — opt-in baseline state emission (
--baseline-emit-state)The first run seeds a baseline with
deltas: [], so state that already exists at baseline (a PR already conflicting, already CI-blocked) never produces a delta until the PR changes again — a stuck PR could stay invisible forever.--entities) with a new closed-set classbaseline-state—from: null,tothe freshly observed fingerprint,summarypresent for PR deltas under--summaries.idis content-addressed under the existing scheme (which excludesclasseswhento != null), so re-baselining over unchanged state yields identical ids — idempotent consumers dedupe for free.10withbaseline: trueand a non-emptydeltasarray. Contract's "when baseline is true, deltas is always []" sentence scoped to runs without the flag; exit-code section notes watchers chaining on exit10feed the baseline report like any other.baseline-stateas newly created (mirrorsfirst-seen).Consumer fit (
gh-delta-orca)Maps
mergeStateStatus: behind→behind_baseblockage; requiresclean | unstable | has_hooks(or field absent) for its ready signal; feedsbaseline-statedeltas through its normal pipeline unchanged (it already tolerates unknown classes).Tests & verification
npm run check(lint + format:check + test) is clean.mergeStateStatus+ boundary default; fingerprint stores-but-strips it (no phantom delta on upgrade); everymergeStateStatusenum value normalizes;--help-jsonadvertises the field/enum/flag;--summariessurfacesbehind; baseline-state off/on, id-stability across re-baseline, and--summariesinteraction; the frozen contract-class guardrail forced thetext-outputsuggested-action entry.